home *** CD-ROM | disk | FTP | other *** search
/ Amiga Game-Power / Amiga Game-Power.iso / power games ii / tetrix / ifflib / ifflib.doc < prev    next >
Text File  |  1994-05-20  |  11KB  |  419 lines
  1.  
  2.          THE UNIVERSAL IFF LIBRARY FOR THE AMIGA
  3.  
  4.         BY CHRISTIAN A. WEBER, ZURICH/SWITZERLAND
  5.  
  6.  
  7. THIS PROGRAM IS IN THE PUBLIC DOMAIN. IT MAY BE FREELY DISTRUBUTED, COPIED
  8. AND USED FOR COMMERCIAL OR NON-COMMERCIAL PURPOSES.  IT MAY BE DISTRIBUTED
  9. WITH OR WITHOUT THIS DOCUMENTATION FILE.
  10.  
  11. TO MAINTAIN COMPATIBILITY,  YOU SHOULD NOT MAKE ANY CHANGES ON THE LIBRARY
  12. ITSELF. UPDATES WILL BE RELEASED BY THE AUTHOR.
  13.  
  14.  
  15. OVERVIEW OF THE LIBRARY FUNCTIONS (Version 15.3)
  16. ------------------------------------------------
  17.  
  18. Name        Offset    Description
  19.  
  20. OpenIFF        -30    Allocate memory for an IFF-file and load it
  21. CloseIFF    -36    Finish access to an IFF-file and deallocate memory
  22. FindChunk    -42    Find a specific chunk in an IFF file
  23. GetBMHD        -48    Find the BitMapHeader of an ILBM file
  24. GetColorTab     -54    Find CMAP chunk, convert it to an Amiga ColorTable
  25. DecodePic    -60    Decode the BODY of an ILBM file into a BitMap
  26. SaveBitMap    -66    Save the contents of a BitMap as an IFF-file
  27. SaveClip    -72    Save a part of a BitMap as an IFF-file
  28. IffError    -78    Get detailed error descrpition if a routine fails
  29. GetViewModes     -84    Get the Amiga-specific ViewModes-Word
  30. (to be continued)
  31.  
  32.  
  33.  
  34. DETAILED DESCRIPTION OF THE LIBRARY FUNCTIONS
  35. ---------------------------------------------
  36.  
  37. (This documentation was translated from German to English in half an hour,
  38. so please be tolerant!)
  39.  
  40. IFF/OpenIFF                                                       IFF/OpenIFF
  41.  
  42.    NAME
  43.     OpenIFF -- allocate memory for an IFF-file and read it
  44.  
  45.    SYNOPSIS
  46.     ifffile = OpenIFF(filename)
  47.      D0                A0
  48.  
  49.    OFFSET
  50.         -30
  51.  
  52.    FUNCTION
  53.     This function opens a file on a disk and looks whether it's an IFF
  54.     file or not. If it is an IFF file, memory is allocated and the file
  55.     is read into memory. If the file is of the type '8SVX', it will be
  56.     loaded into CHIP memory.
  57.     If an error occurs, 0 is returned, and you can call IffError() to
  58.     get the error number.
  59.  
  60.    INPUTS
  61.     filename - Pointer to a null-terminated string
  62.  
  63.    RESULT
  64.     ifffile - 'FileHandle', points to the beginning of the IFF file
  65.     ("FORM...."), 0 if unsuccessful.
  66.  
  67.    SEE ALSO
  68.     CloseIFF
  69.  
  70.    BUGS
  71.     None
  72.  
  73.  
  74.  
  75.  
  76. IFF/CloseIFF                                                     IFF/CloseIFF
  77.  
  78.    NAME
  79.     CloseIFF -- finish access to an IFF-file and deallocate memory
  80.  
  81.    SYNOPSIS
  82.     CloseIFF(ifffile)
  83.               A1
  84.  
  85.    OFFSET
  86.         -36
  87.  
  88.    FUNCTION
  89.     Returns the memory previously allocated by OpenIFF().
  90.  
  91.    INPUTS
  92.     ifffile - IFF file pointer, from OpenIFF()
  93.  
  94.    RESULT
  95.     none
  96.  
  97.    SEE ALSO
  98.     OpenIFF
  99.  
  100.    BUGS
  101.     If A1 contains garbage, an 81000005 Guru will visit you...
  102.  
  103.  
  104.  
  105. IFF/FindChunk                                                   IFF/FindChunk
  106.  
  107.    NAME
  108.     FindChunk -- find an IFF-chunk
  109.  
  110.    SYNOPSIS
  111.     chunk = FindChunk(ifffile,chunkname)
  112.      D0               A1       D0
  113.  
  114.    OFFSET
  115.         -42
  116.  
  117.    FUNCTION
  118.     Find a specific chunk in an IFF file
  119.  
  120.    INPUTS
  121.     ifffile - IFF file pointer, returned by OpenIFF()
  122.     chunkname - 4 characters packed ASCII ('BODY', 'VHDR' ...)
  123.  
  124.    RESULT
  125.     Pointer to the beginning of the chunk (that means to the chunk
  126.     name itself, followed by the chunk size), zero if chunk not found
  127.  
  128.    SEE ALSO
  129.     GetBMHD, GetColorTab
  130.  
  131.    BUGS
  132.     none
  133.  
  134.  
  135.  
  136.  
  137.  
  138. IFF/GetBMHD                                                       IFF/GetBMHD
  139.  
  140.    NAME
  141.     GetBMHD -- find a BitMapHeader of an IFF-file
  142.  
  143.    SYNOPSIS
  144.     header = GetBMHD(ifffile)
  145.      D0              A1
  146.  
  147.    OFFSET
  148.         -48
  149.  
  150.    FUNCTION
  151.     Returns a pointer to a 'BitMapHeader' structure as defined in
  152.     iff.h and iff.i
  153.  
  154.    INPUTS
  155.     ifffile - IFF file pointer, returned by OpenIFF()
  156.  
  157.    RESULT
  158.     Pointer to the BitMapHeader, or 0 if no BMHD chunk found
  159.  
  160.    SEE ALSO
  161.     FindChunk, GetColorTab
  162.  
  163.    BUGS
  164.     none
  165.  
  166.  
  167.  
  168.  
  169. IFF/GetColorTab                                               IFF/GetColorTab
  170.  
  171.    NAME
  172.     GetColorTab -- find a CMAP chunk and convert it to a ColorTable
  173.  
  174.    SYNOPSIS
  175.     count = GetColorTab(ifffile,colortable)
  176.      D0                  A1      A0
  177.  
  178.    OFFSET
  179.         -54
  180.  
  181.    FUNCTION
  182.     Searches the CMAP chunk of an IFF file and converts it, if it's
  183.     there, to an Amiga color table structure. This colortable can
  184.     directly be used as a parameter for the LoadRGB4() function.
  185.  
  186.    INPUTS
  187.     ifffile - IFF file pointer, returned by OpenIFF()
  188.     colortable - Pointer to a block of memory which must be large
  189.                  enough to hold the colortable (2 bytes per color)
  190.  
  191.    RESULT
  192.     Number of colors actually found, or zero if the file has no
  193.     CMAP chunk
  194.  
  195.    SEE ALSO
  196.     FindChunk, GetBMHD
  197.  
  198.    BUGS
  199.     the colortable must be WORD aligned (this isn't really a bug)
  200.  
  201.  
  202.  
  203.  
  204. IFF/DecodePic                                                   IFF/DecodePic
  205.  
  206.    NAME
  207.     DecodePic -- decode an IFF-BODY into a BitMap
  208.  
  209.    SYNOPSIS
  210.     bitmap = DecodePic(ifffile,bitmap)
  211.      D0                 A1      A0
  212.  
  213.    OFFSET
  214.         -60
  215.  
  216.    FUNCTION
  217.     Decodes and decrunches a picture into the BitMap you supplied.
  218.     If the picture is larger than your BitMap's planes, it will be
  219.     truncated. If your BitMap is larger than the picture, the picture
  220.     will be drawn into the top left corner of your BitMap.
  221.     If the picture has more planes (colors) than your BitMap, the
  222.     operation will fail and 0 will be returned.
  223.  
  224.    INPUTS
  225.     ifffile - IFF file pointer, from OpenIFF()
  226.     bitmap  - Pointer to a properly initialized BitMap structure:
  227.           bm_Planes[] must point to valid BitPlanes,
  228.           bm_Depth contains the number of planes.
  229.           bm_Width and bm_Height must be set according to the
  230.           size of your bit planes.
  231.  
  232.    RESULT
  233.     Non-zero if  OK, 0 if error, Call IffError() to know the reason
  234.     of the failure
  235.  
  236.    BUGS
  237.     The width of the IFF picture (in pixels) must be a multiple of 8
  238.     (I've never seen a picture which didn't obey this rule!)
  239.  
  240.  
  241.  
  242. IFF/SaveBitMap                                                 IFF/SaveBitMap
  243.  
  244.    NAME
  245.     SaveBitMap -- save the planes of a BitMap as an IFF-file
  246.  
  247.    SYNOPSIS
  248.     result = SaveBitMap(filename,bitmap,colortable,flags)
  249.      D0                  A0       A1     A2         D0
  250.  
  251.    OFFSET
  252.         -66
  253.  
  254.    FUNCTION
  255.     Save the planes of a BitMap as an IFF-file, optionally with a
  256.     colortable. The IFF file will contain the following chunks:
  257.  
  258.     FORM  -  The IFF header, with the type ILBM
  259.     BMHD  -  The BitMap Header structre
  260.     CMAP  -  The color map, this chunk is omitted if colortable is zero
  261.     CAMG  -  The Amiga ViewModes word, contains the special ViewModes
  262.              information (HAM, LACE, HIRES ...)
  263.     BODY  -  The (crunched or uncompressed) picture
  264.  
  265.    INPUTS
  266.     filename    - Name of the IFF file to create
  267.     bitmap      - Pointer to the BitMap holding your picture
  268.     colortable  - Pointer to an Amiga ColorTable structure or zero
  269.                   (if colortable = 0, no CMAP chunk will be generated).
  270.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  271.                          0 = Save the file uncompressed
  272.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  273.                          0 = This is a normal or Extra-Halfbrite picture
  274.  
  275.    RESULT
  276.     Non-zero if successful, 0 if error, Call IffError() to know the
  277.     reason of the failure
  278.  
  279.    SEE ALSO
  280.     SaveClip
  281.  
  282.  
  283.  
  284.  
  285.  
  286. IFF/SaveClip                                                     IFF/SaveClip
  287.  
  288.    NAME
  289.     SaveClip -- save a part of a BitMap as an IFF-file
  290.  
  291.    SYNOPSIS
  292.     result = SaveClip(filename,bitmap,coltab,flags,xoff,yoff,width,height)
  293.      D0                A0       A1     A2     D0    D1   D2   D3    D4
  294.  
  295.    OFFSET
  296.         -72
  297.  
  298.    FUNCTION
  299.     Save a part of a BitMap as an IFF file
  300.  
  301.    INPUTS
  302.     filename    - Name of the IFF file to create
  303.     bitmap      - Pointer to the BitMap holding your picture
  304.     colortable  - Pointer to an Amiga ColorTable structure or zero
  305.                   (if colortable = 0, no CMAP chunk will be generated).
  306.     flags       - Bit 0: 1 = Use the "CmpByteRun1" compression algorythm,
  307.                          0 = Save the file uncompressed
  308.                       Bit 7: 1 = This is a HAM (Hold and modify) picture
  309.                          0 = This is a normal or Extra-Halfbrite picture
  310.     xoff        - X offset of the clip to be saved (bytes from the left)
  311.     yoff        - Y offset of the clip to be saved (lines from the top)
  312.     width       - width in bytes of the rectangle
  313.     height      - height in lines of the rectangle
  314.  
  315.    RESULT
  316.     Non-zero if successful, 0 if error, Call IffError() to know the
  317.     reason of the failure
  318.  
  319.    SEE ALSO
  320.     SaveBitMap
  321.  
  322.    BUGS
  323.     The width of the rectangle will be rounded to WORD boundaries,
  324.     because DPAINT® wants it!
  325.  
  326.  
  327.  
  328. IFF/IffError                                                     IFF/IffError
  329.  
  330.    NAME
  331.     IffError -- Get detailed error descrpition
  332.  
  333.    SYNOPSIS
  334.     error = IffError()
  335.     D0
  336.  
  337.    OFFSET
  338.         -78
  339.  
  340.    FUNCTION
  341.     If one of the above functions returns zero, you can call IffError()
  342.     to know the reason for the failure. An error code is returned,
  343.     please refer to the files 'iff.h' or 'iff.i' for the complete
  344.     list of errors!
  345.  
  346.    INPUTS
  347.     none
  348.  
  349.    RESULT
  350.     Error-number generated by the latest function call, or zero if
  351.     no error
  352.  
  353.     Cuurently the following numbers are used:
  354.  
  355.     Nr.  Symbol             Function     Description
  356.  
  357.     16   IFF_CANTOPENFILE   OpenIFF()    File not found
  358.     17   IFF_READERROR      OpenIFF()    Read() returned an error
  359.     18   IFF_NOMEM          OpenIFF()    Not enough memory for the file
  360.     19   IFF_NOTIFF         OpenIFF()    File is not IFF
  361.     20   IFF_WRITEERROR    SaveBitMap() Cannot write the file
  362.  
  363.     24   IFF_NOILBM         DecodePic()  IFF file is not an ILBM file
  364.     25   IFF_NOBMHD         DecodePic()  BMHD chunk not found
  365.     26   IFF_NOBODY         DecodePic()  BODY chunk not found
  366.     27   IFF_TOOMANYPLANES  DecodePic()  Picture has more planes than
  367.                                          your BitMap
  368.     28   IFF_UNKNOWNCOMPRESSION  "       Unknown compression type
  369.  
  370.     -1   IFF_BADTASK        A task which did not open the IFF library
  371.                             tried to call IffError(). Since the IFF
  372.                             library is capable of multi-tasking, the
  373.                             error-values are stored for each task
  374.                             separately.
  375.  
  376.    SEE ALSO
  377.  
  378.    BUGS
  379.     If you don't close the IFF library at the end of your program
  380.     (using CloseLibrary()) the error node will not be freed. The
  381.     same task will then not be able to re-open the iff.library!!!
  382.  
  383.  
  384.  
  385. IFF/GetViewModes                                             IFF/GetViewModes
  386.  
  387.    NAME
  388.     GetViewModes -- Get Amiga-specific ViewModes-Word
  389.  
  390.    SYNOPSIS
  391.     viewmodes = GetViewModes(ifffile)
  392.     D0                        A1
  393.  
  394.    OFFSET
  395.         -84
  396.  
  397.    FUNCTION
  398.     Searches the IFF file for a 'CAMG' chunk which holds the view modes
  399.     information. If there is no CAMG chunk, the view modes are calcu-
  400.     lated using the information in the BitMapHeader structure.
  401.     You can set the result of GetViewModes() directly into the
  402.     ns_ViewModes field of a NewScreen structure!
  403.  
  404.    INPUTS
  405.     ifffile - IFF file pointer, returned from OpenIFF()
  406.  
  407.    RESULT
  408.     viewmodes - WORD containing the view modes (HAM, LACE, HIRES ...)
  409.  
  410.    SEE ALSO
  411.  
  412.    BUGS
  413.     If the IFF file has no CAMG chunk and 6 bitplanes, the HAM bit
  414.     will be set. This is not always correct since the picture could
  415.     be in the Extra Halfbrite mode
  416.  
  417.  
  418. The file 'ShowIff.c' shows you how to use the IFF library from C.
  419.